Antag Selection Logging - #5847

Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.

Summary

Improves antagonist-selection observability without changing gameplay mechanics or player-facing behavior.

• Adds round-aware antagonist-selection metrics for Grafana grouping.
• Records successful late-join antagonist assignments.
• Extends TryAssignNextAvailableAntag to return the assigned antagonist definition.
• Preserves the existing public overload through delegation.
• Moves Starlight-specific metrics and enforcement logic into a partial class extension.

User impact

There are no gameplay or player-facing changes. The changes affect server metrics and logging.

Notable changes

• Content.Server/Antag/AntagSelectionSystem.cs

  • Removes Starlight-specific metrics and enforcement code from the upstream file.
  • Keeps the upstream antagonist-selection system focused on core behavior.
  • Adds round-restart cleanup event handling.

• Content.Server/Antag/AntagSelectionSystem.Starlight.cs

  • Adds Prometheus metrics labelled by round, rule, type, and state.
  • Adds metric cleanup on round restart.
  • Tracks initial selections and late-join assignments.
  • Preserves target enforcement, retry handling, replacement assignment, ghost-role spawning, and loadout selection.

• Content.Server/Antag/AntagSelectionSystem.API.Assignment.cs

  • Adds an assignment overload with an out antagonist definition.
  • Records successful late-join assignments.
  • Keeps the existing public overload through delegation.

Risk areas

• The round label increases Prometheus series cardinality.
• Existing Grafana queries and metric consumers may need to handle the new label.
• Late-join metrics must remain limited to successful antagonist creation.
• Metric cleanup must remove prior-round series without affecting current-round reporting.
• Moving enforcement logic into a partial class can cause regressions if upstream changes alter shared method contracts or selection flow.
• Removing the implementation from the upstream file and maintaining it in a Starlight extension can increase divergence during future upstream merges.

Guideline gaps

• The PR body does not explain why the Starlight-specific implementation must remain in a separate partial file.
• The new Starlight file does not visibly document Starlight ownership or the reason for duplicating the upstream selection implementation.
• The PR body does not describe the design impact of moving the implementation out of the upstream file and reintroducing it in a Starlight extension.

Walkthrough

Antag selection logic moved into a Starlight partial class. The system enforces antag targets, handles replacements and ghost roles, records selection metrics, and records the assigned definition for late-join assignments.

Changes

Antag selection enforcement and metrics

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 42ef4

The PR adds round-scoped antagonist selection telemetry and cleanup without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant ActiveTick
  participant EnforceAntagTargets
  participant WeightedPlayerPool
  participant GhostRoleSpawner
  participant SelectionMetrics
  ActiveTick->>EnforceAntagTargets: enforce antag targets
  EnforceAntagTargets->>WeightedPlayerPool: assign eligible players
  WeightedPlayerPool-->>EnforceAntagTargets: return assignment results
  EnforceAntagTargets->>GhostRoleSpawner: fill remaining target slots
  GhostRoleSpawner-->>EnforceAntagTargets: return spawning result
  EnforceAntagTargets->>SelectionMetrics: update selection counts

Suggested reviewers: walksanatora

❌ Failed checks (1 warning)

• X
• Mastodon
• Reddit
• LinkedIn